home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / strlist3 / strlist.h < prev    next >
Text File  |  1996-02-26  |  7KB  |  223 lines
  1. /* File strlist.h Copyright (C) 1995, 1996 by John R. Montbriand.  All Rights Reserved. */
  2.  
  3. #ifndef __STRLIST__
  4. #define __STRLIST__
  5.  
  6. /* File strlist.h
  7.  
  8.     Copyright (C) 1995, 1996 by John Montbriand.  All Rights Reserved.
  9.     
  10.     Distribute freely in areas where the laws of copyright apply.
  11.     
  12.     Use at your own risk.
  13.     
  14.     Do not distribute modified copies.
  15.     
  16.     These various string list libraries are for free!
  17.     
  18.     See the file strlist.txt for details.
  19.     
  20. */
  21.  
  22. #include <Types.h>
  23. #include <Menus.h>
  24. #include <Lists.h>
  25.  
  26.  
  27. /* version of this library */
  28.  
  29. #define kStrListVersion 2
  30.  
  31.  
  32. /* SLUSECASE determines if the routines that compare strings are
  33.     case sensitive or not.  if SLUSECASE is true, all comparisons
  34.     are case sensitive, otherwise, if SLUSECASE is false, all comparisons
  35.     are non case sensitive. */
  36.  
  37. #ifndef SLUSECASE
  38. #define SLUSECASE false
  39. #endif
  40.  
  41. #ifdef __cplusplus
  42. extern "C" { 
  43. #endif
  44.  
  45.  
  46. /* routines for creating and retrieving string lists */
  47.  
  48. /* NewStringList makes a new string list containing no strings */
  49. Handle NewStringList(void);
  50.  
  51. /* MakeStringList makes a new string list containing n strings
  52.     proviced as c style strings in the ... parameter list. */
  53. Handle MakeStringList(long n, ...);
  54.  
  55. /* GetStringList  retrieves the STR# resource with the given ID. */
  56. Handle GetStringList(short id);
  57.  
  58. /* Get1StringList  retrieves the STR# resource with the given ID
  59.     searching only the first resource file in the resource chain. */
  60. Handle Get1StringList(short id);
  61.  
  62. /* DisposeStringList recovers the memory occupied by a string list.
  63.     if the handle refers to a resource, ReleaseResource is called,
  64.     otherwise DisposeStringList calls DisposeHandle. */
  65. void DisposeStringList(Handle list);
  66.  
  67.  
  68.  
  69. /* routines for retrieving information from string lists */
  70.  
  71. /* StringListSize returns the number of strings in the STR#. */
  72. short StringListSize(Handle list);
  73.  
  74. /* StringListElt returns a pointer to a string in a string list.
  75.     StringListElt returns a pointer to the string data contained
  76.     in the string list handle so be sure to lock the handle
  77.     before calling this function. */
  78. StringPtr StringListElt(Handle list, short elt);
  79.  
  80. /* RetrieveIndString copies the indicated string list element from
  81.     the string list into the string pointed to by the_string.
  82.     RetrieveIndString returns the value passed in the third
  83.     parameter, or NULL if the index was out of bounds. */
  84. StringPtr RetrieveIndString(Handle list, short elt, StringPtr the_string);
  85.  
  86.  
  87.  
  88. /* routines for using string list maps */
  89.  
  90. /* MakeStringListMap locks the string list handle in memory
  91.     and returns a handle to an array of string pointers that
  92.     refer to consecutive elements in the string list.
  93.     if the there is not enough memory to create the array,
  94.     the the list is not locked and NULL is returned. */
  95. StringPtr** MakeStringListMap(Handle list);
  96.  
  97. /* MakeSortedStringListMap is identical to MakeStringListMap
  98.     except the map returned is sorted in ascending, alphabetical
  99.     order.  if SLUSECASE is true, case sensitive ordering is used. */
  100. StringPtr** MakeSortedStringListMap(Handle list);
  101.  
  102. /* MapStringListElt returns a pointer to a string in a string list
  103.     using a string list map returned by MakeStringListMap. */
  104. StringPtr MapStringListElt(StringPtr** string_map, short elt);
  105.  
  106. /* WithStringList macro.  you must declare a variable of type
  107.     StringPtr** and provide it as the map parameter before
  108.     defining this macro.  */
  109. #define WithStringList(stringlist, map) \
  110.     for(map=MakeStringListMap(stringlist);map!=NULL; \
  111.     DisposeHandle((Handle)(map)), HUnlock(stringlist), map=NULL)
  112.  
  113. /* WithSortedStringList is identical to the WithStringList macro
  114.     except it calls MakeSortedStringListMap */
  115. #define WithSortedStringList(stringlist, map) \
  116.     for(map=MakeSortedStringListMap(stringlist);map!=NULL; \
  117.     DisposeHandle((Handle)(map)), HUnlock(stringlist), map=NULL)
  118.  
  119.  
  120.  
  121.  
  122. /* for removing elements from string lists */
  123.  
  124. /* StringListRemove removes the indicated string from the string list */
  125. void StringListRemove(Handle list, short elt);
  126.  
  127. /* ClearStringList empties the string list */
  128. void ClearStringList(Handle list);
  129.  
  130.  
  131.  
  132. /* routines for adding strings to string lists */
  133.  
  134. /* StringListInstall installs the string in the list at the indicated
  135.     element position. */
  136. void StringListInstall(Handle list, short elt, StringPtr s);
  137.  
  138. /* StringListAppend adds the string s to the end of the string list. */
  139. void StringListAppend(Handle list, StringPtr s);
  140.  
  141. /* StringListPrepend adds the string s to the front of the string list. */
  142. void StringListPrepend(Handle list, StringPtr s);
  143.  
  144.  
  145.  
  146. /* routines for inserting strings into alphabetically sorted string lists */
  147.  
  148. /* StringListInsert inserts the string into the string list
  149.     such that the string list remains alphabetically sorted.
  150.     if SLUSECASE is true, case sensitive ordering is used.
  151.     returns the index of the inserted string. */
  152. short StringListInsert(Handle list, StringPtr s);
  153.  
  154. /* StringListRInsert inserts a string into a string list sorted
  155.     in descending order. if SLUSECASE is true, case sensitive
  156.     ordering is used. the index of the inserted string is returned. */
  157. short StringListRInsert(Handle list, StringPtr s);
  158.  
  159.  
  160.  
  161. /* for searching for strings in string lists */
  162.  
  163. /* FindStringList finds the index of the string in the list.  
  164.     comparisons are case sensitive if SLUSECASE is true. if
  165.     it's not there,  the function returns zero. */
  166. short FindStringList(Handle list, StringPtr s);
  167.  
  168.  
  169.  
  170. /* utility functions for working with string lists. */
  171.  
  172. /* uncomment the following to allow the menu manager to interpret
  173.     special characters when string list elements are added to menus.
  174.     by default, StringListToMenu does not allow this to happen. */
  175. /* #define INTERPRETMENUCHARS 1 */
  176.  
  177. /* StringListToMenu converts the string list into a menuhandle
  178.     suitable for putting in the menubar on using as a popup. */
  179. MenuHandle StringListToMenu(Handle list, short id, StringPtr name);
  180.  
  181.  
  182. /* StringListToList converts the string list into a menuhandle
  183.     suitable for putting in the menubar on using as a popup. */
  184. void StringListToList(Handle list, ListHandle the_list);
  185.  
  186.  
  187.  
  188.  
  189. /* routines for using string lists as sets of strings.  each string
  190.     list is treated as a set of strings.  all string comparisons
  191.     are control by the SLUSECASE variable. */
  192.  
  193. /* StringListUnion returns a new string list containing all of the strings
  194.     appearing in both string lists, or NULL if an error occurs.  */
  195. Handle StringListUnion(Handle A, Handle B);
  196.  
  197. /* StringListIntersection returns a new string list containing
  198.     the strings that appear in both string lists, or NULL
  199.     if an error occurs. */
  200. Handle StringListIntersection(Handle A, Handle B);
  201.  
  202. /* StringListDifference returns a new string list containing
  203.     all of the strings appearing in the union of A and B that
  204.     do not appear in the intersection of A and B. */
  205. Handle StringListDifference(Handle A, Handle B);
  206.  
  207. /* StringListSubset returns true if the strings contained in
  208.     the string list subs are a subset of the strings contained
  209.     in the string list 'list' */
  210. Boolean StringListSubset(Handle A, Handle B);
  211.  
  212. /* StringListEquivalent returns true if string list A
  213.     contains the same set of strings as string list B. */
  214. Boolean StringListEquivalent(Handle A, Handle B);
  215.  
  216. #ifdef __cplusplus
  217. };
  218. #endif
  219.  
  220. #endif
  221.  
  222. /* end of file strlist.h */
  223.